home *** CD-ROM | disk | FTP | other *** search
/ MacFormat 1996 January / macformat-033.iso / mac / Shareware City / Developers / ABox.v1.8 / Header Files / ABoxDefs.h < prev    next >
Encoding:
Text File  |  1995-05-23  |  15.9 KB  |  403 lines  |  [TEXT/MMCC]
  1. /*    
  2.     Copyright © 1991-1995 by TopSoft Inc.  All rights reserved.
  3.  
  4.     You may distribute this file under the terms of the TopSoft
  5.     Artistic License, accompanying this package.
  6.     
  7.     This file was developed by George (ty) Tempel in connection with TopSoft, Inc..
  8.     See the Modification History for more details.
  9.  
  10. Product
  11.     About Box
  12.  
  13. FILE
  14.     ABoxDefs.h
  15.  
  16. NAME
  17.     ABoxDefs.h, part of the ABox project source code,
  18.     responsible for handling the AboutBox stuff.
  19.  
  20. DESCRIPTION
  21.     This file contains defines for the about box modules.
  22.     
  23. DEVELOPED BY
  24.     George (ty) Tempel                netromancr@aol.com
  25.     All code in this file, and its associated header file was
  26.     Created by George (ty) Tempel in connection with the TopSoft, Inc.
  27.     "FilterTop" application development, except where noted.
  28.  
  29. CARETAKER - George (ty) Tempel <netromancr@aol.com>
  30.      Please consult this person for any changes or suggestions to this file.
  31.  
  32. MODIFICATION HISTORY
  33.  
  34.     dd mmm yy    -    xxx    -    patchxx: description of patch
  35.     ?? Oct 92    -    ty    -    Initial Version Created
  36.     ?? Jul 93    -    ty    -    d18, d19 fixes
  37.     05-oct-93    -    ty    -    d25/26 changes for apple recommended
  38.                             greys for the 3d effects (see develop #15)
  39.     19-nov-93    -    ty    -    d26 changes for improved update handling
  40.     26-jan-94    -    ty    -    1.0a3 changed "int" to "short int"
  41.     26-jan-94    -    ty    -    1.0a3 conversions for PowerPC/Universal-Headers conversion
  42.     01-feb-94    -    ty    -    1.0a3 changes to remove "register" keyword, remove use of "nrequire"
  43.                             and "require" error checking as sometimes they are confusing,
  44.                             fixed possible bug when dismissing the dialog while a movie
  45.                             is playing, and other small things. Mostly tried to edit
  46.                             the code to comply with the bulk of the Coding Standards document
  47.                             that Jim Brunner produced (nice work jim!)
  48.     22-feb-94    -    ty    -    1.0a4 patches to work better with universal headers, clear
  49.                             up some minor stuff, add FTQsort for universal header
  50.                             portability. Fixed some logic to better deal with the
  51.                             user having moved or eliminated our access to the FTSlides
  52.                             folder.
  53.     28-feb-94    -    ty    -    1.0a4 work to eliminate FTQsort (found a better
  54.                             way of fixing the header file collision created by the
  55.                             introduction of Apple Universal Headers into the Symantec
  56.                             compiler tree). Fixed up some of the user safety checks,
  57.                             return values, etc. Cleaned up more of the Universal Header
  58.                             support, and provided Universal Headers support in the
  59.                             ModalDialog() use.
  60.     09-mar-94    -    ty    -    1.0a4p2 Created functions:
  61.                             CreateTopicList(), CreateSlideList(), CreateSlideNumbers()
  62.                             to simplify dynamic memory management; GetABoxDialog(), 
  63.                             SetABoxDialog(), GetABoxList(), SetABoxList(), GetABoxText(),
  64.                             SetABoxText(), GetABoxListVScroll(), SetABoxListVScroll(),
  65.                             GetABoxListHScroll(), SetABoxListHScroll() for abox structure
  66.                             management
  67.     17-mar-94    -    ty    -    1.0a5 applied edits to ensure all calls check their
  68.                             parameters for validity and have AssertStr() statements
  69.                             that can be conditionally compiled. Also, applied the
  70.                             multithreaded modal dialog tips from _develop_ #17, p 89-90. Also
  71.                             started to document the daylights out of everything.
  72.     14-apr-94    -    ty    -    metropolis edits: adding kABTopicSlideResource 'TSAb' support
  73.                             for all slide/topic files including the application. Any file
  74.                             that should appear in the topic list _must_ have a TSAb resource
  75.                             within it (and only one!) that is a 1-based list of all
  76.                             resource family ID's to use as slides, in the order of
  77.                             appearance. So a TSAb resource that should display
  78.                             resources of ID's 400, 128, 345 should specify the
  79.                             slide ID's 400, 128, 345 in that order. No sorting is
  80.                             performed by the abox. Furthermore, the application fork
  81.                             should have a TSAb resource within it to designate
  82.                             'primary slides' (which we had called default slides). Those
  83.                             slides are always attached to the "About this application..."
  84.                             topic at the top of the topic list.
  85.     28-apr-94    -    ty    -    1.0a9 edits: cleaned up constants in code, document more
  86.                             functionality and ensure error checking.
  87.     2-may-94    -    ty    -    1.0a9p2 edits: restored the original TS copyright header
  88.     3-may-94    -    ty    -    1.0a9p3 edits: added calling chain information
  89.     5-may-94    -    ty    -    1.0a9p4 edits: added speech manager support for clicking
  90.                             on the slide field area. If there is a kABstringResource
  91.                             and the speech manager is present then the 'title' will
  92.                             be spoken in the system's default voice. Cool! As such,
  93.                             I have added the functions IsSpeechAvailable() and DoSpeaking()
  94.     6-jun-94    -    ty    -    1.0a9p7 edits: changed function return type of CountAndLoadElementResources
  95.                             to OSErr...the ResourceInfoPtr was redundant since it is contained 
  96.                             within the SlideListPtr structure
  97.     8-jun-94    -    ty    -    1.0a9p8 edits: THE BIG ONE!
  98.                             1.    I mostly cleaned up some loop conditionals and some error
  99.                                 checking in order to debug the problem of the Great Crashing
  100.                                 About Box under the PowerPC Mac 68k emulator. Most visibly
  101.                                 I have reorganized the ABox source into many source files
  102.                                 of much smaller and more manageable sizes. A few key loop
  103.                                 conditionals were poorly constructed and _just_might_
  104.                                 cause intermittent problems. I have tested the code on a
  105.                                 PowerMac 6100/60-AV 8/250 with Metrowerks DR/3 release
  106.                                 and it works without problems. In light of the new
  107.                                 source for the ABox, you should remove any FTAboutBox.c
  108.                                 and FTAboutBox.h files that you have in your project and
  109.                                 incorporate the files in this distribution. If you wish to
  110.                                 keep things neater, leave the new ABox code in the subfolders
  111.                                 provided in this distribution.
  112.                                 
  113.                             2.    I have changed the cosmetics of the topic list. I am letting
  114.                                 the List Manager determine the best vertical size for the cells,
  115.                                 but I am adjusting the height of the list to avoid cutting off
  116.                                 any cells part way. I have always used the List Manager option to
  117.                                 auto-scroll to the current cell, but if even a single pixel of
  118.                                 the current cell is showing then the auto-scroll option has
  119.                                 no effect. What I do now is downward-adjust (shorten) the height
  120.                                 of the list to force the "cut-off" topic out of sight and let
  121.                                 the List Manager take over. Long and short of it: it works fine now.
  122.                             
  123.                             3.    Once debugging on the PowerMac (wow is it fast! even when
  124.                                 debugging the 68k abox code!) I noticed that I had a call
  125.                                 duplicated in a body, which caused all slide elements to actually
  126.                                 be processed twice...with sound resources this is most noticeable,
  127.                                 or rather only noticeable, on a PowerMac, since the sound starts
  128.                                 to play, is killed, then played again (all other things are
  129.                                 way to fast to detect). The duplicated call came from an editing
  130.                                 session where code was duplicated instead of moved. I removed the
  131.                                 duplicate and now it all works.
  132.                                 
  133.                             4.    I found a rather severe bug in the code regarding the
  134.                                 usage of the external (to the abox) window updater function.
  135.                                 I forgot to make edits for UPP/PowerPC usage, and as such
  136.                                 the thing just might have crashed and burned on PPC boxes in
  137.                                 native mode. I believe that I have corrected the problem.
  138.                                 
  139.                             5.    The calling code (in our case, the function inside FTMenus.c)
  140.                                 for the ABox _must_ create the external window updater UPP.
  141.                                 Previously I had the calling code pass the function pointer,
  142.                                 but in the spirit PPC-dom, the caller should create the UPP
  143.                                 and hand the UPP over to the abox.
  144.  
  145.     20-july-94    -    ty    -    initial version for ABox Project released
  146.     23-may-95    -    ty    -    changes for compatibility with the CodeWarrior CW6
  147.                             release and the associated Universal Headers from Apple:
  148.                             most methods that returned references now have "Ref" at
  149.                             the end of their methods names to prevent possible collisions
  150.                             with datatypes and classes of the same name (older versions
  151.                             of the compiler didn't have a problem with this).
  152. */
  153.  
  154. /*===========================================================================*/
  155.  
  156. /*========== Exclusion Macros ============*/
  157.  
  158. #pragma    once
  159.  
  160. #ifndef    _ABoxDefs_
  161. #define    _ABoxDefs_
  162.  
  163.  
  164. /*============ Header Files ==============*/
  165.  
  166.  
  167. /*================ Macros ================*/
  168.  
  169.  
  170.  
  171. /*============== Constants ===============*/
  172.  
  173. //    dialog box & items
  174.  
  175. //    _DialogDispatch is the trap for the new (system 7) dialog manager
  176. //    calls SetDefaultItem, SetCancelItem, SetCursorTracking, which make
  177. //    life a little easier for modal dialog programmers.
  178. #define     _DialogDispatch                     0xAA68    // 1.0a2 SJ moved over from FTAboutBox.c
  179.  
  180. //    Unimplemented Trap number
  181. #define     kABUnimplTrap        0x9f        //    The "unimplmented" trap num
  182.  
  183.  
  184. //    kABownerNameString and kABmachineNameString are what were referred to
  185. //    as the "chooser name" information from pre-system 7 systems. These
  186. //    string resources come from the Sharing Setup control panel and are used
  187. //    by the about box to place the user's name into the topic list
  188. //    to personalize the about box.
  189. #define        kABownerNameString                    -16096
  190. #define        kABmachineNameString                -16413
  191.  
  192. //    dialog and dialog placement defines
  193. //
  194. //    kABreduceFactor is used by ScaleRectToFit() to adjust the
  195. //    geometry of a rectangular area to better (proportionally) fit
  196. //    a given area.
  197. #define        kABreduceFactor                        (0.75)
  198.  
  199. //    kABdialogSpacing is used by ResizeFields() to adjust the
  200. //    positioning of the various slide elements of the about box.
  201. #define        kABdialogSpacing                    (2)
  202.  
  203. //    kABtextFace, kABtextSize, kABtextFont are used to define
  204. //    the quickdraw text characteristics of the about box dialog
  205. //    elements, particularly the topic list and the slide title.
  206. //    If slide-text items have style records, those are used to
  207. //    define the slide-text, otherwise these characteristics play
  208. //    there are well.
  209. #define        kABtextFace                            (0)    // plain
  210. #define        kABtextSize                            (9)    // size
  211. //    1.0a9p8 ty...changed the kABtextFont to the default application font
  212. //#define        kABtextFont                            (geneva)
  213. #define        kABtextFont                            (applFont)
  214.  
  215. //    kABtitleMaxHeight defines the maximum height of a slide
  216. //    title block in the slide area.
  217. //#define        kABtitleMaxHeight                    (short)(2.5 * kABtextSize)        //    d26 ty
  218.  
  219. //    kABscrollBarWidth and kABscrollBarMinLength are used
  220. //    in the about box code to describe, respectively,
  221. //    the width and minimum length of the scroll bar used by the
  222. //    DoText() function to draw/display text records in the slide area.
  223. #define        kABscrollBarWidth                    (16)
  224. #define        kABscrollBarMinLength                (55)
  225.  
  226.  
  227. //    string resources
  228. //
  229. //    kABStrings is a STR# resource containing some general
  230. //    purpose strings for the about box.
  231. #define        kABStrings                            5001
  232. #define        kABunknownUserInfo                    1
  233. #define        kABfolderSlide                        2
  234. #define        kABdefaultTopicName                    3
  235. #define        kABdefaultTopicNotice                4
  236. #define        kAByourNameHereFile                    5
  237.  
  238. //    the kABfolderTextSlide resource is a TEXT/styl
  239. //    combination that explains why nothing interesting
  240. //    has happened when the user selected a folder in the
  241. //    topic list.
  242. #define        kABfolderTextSlide                    5001
  243.  
  244.  
  245. //    kABErrorStrings is a STR# resource containing
  246. //    all of the error strings used in reporting errors to the
  247. //    user or programmer. This list will most likely continuously
  248. //    grow as features are added to the about box.
  249. #define        kABErrorStrings                        5002
  250. #define        kABErrMemoryAllocated                1
  251. #define        kABErrMemoryDeallocated                2
  252. #define        kABErrMemoryAllocationFailed        3
  253. #define        kABErrNoQuickTime                    4
  254. #define        kABErrDialogMgrTrapsMissing            5
  255. #define        kABErrBadArgStr255                    6
  256. #define        kABErrBadArgStringPtr                7
  257. #define        kABErrBadArgTopicDialogPtr            8
  258. #define        kABErrBadArgListHandle                9
  259. #define        kABErrBadArgNumberOutOfRange        10
  260. #define        kABErrBadArgTopicListPtr            11
  261. #define        kABErrBadArgResourceInfoPtr            12
  262. #define        kABErrBadArgSlideListPtr            13
  263. #define        kABErrDialogItemNumberOutOfRange    14
  264. #define        kABErrBadArgDialogPtr                15
  265. #define        kABErrBadArgControlHandle            16
  266. #define        kABErrBadArgRectPtr                    17
  267. #define        kABErrBadArgFileFolderCountPtr        18
  268. #define        kABErrBadArgShortPtr                19
  269. #define        kABErrBadArgTopicPtr                20
  270. #define        kABErrBadArgSlideNumberPtr            21
  271. #define        kABErrBadResourceHandlingTable        22
  272. #define        kABErrBadResourceHandlingTableCount    23
  273. #define        kABErrProblemsLoadingTopicSlideInfo    24
  274. #define        kABErrProblemsCheckingControlStates    25
  275. #define        kABErrBadArgWindowPtr                26
  276. #define        kABErrBadArgTEHandle                27
  277. #define        kABErrBadUpdateWindowUPP            28
  278. #define        kABErrBadArgEventRecordPtr            29
  279. #define        kABErrProblemsLoadingTopics            30
  280. #define        kABErrProblemsCreatingTopicList        31
  281. #define        kABErrBadArgSoundHandle                32
  282. #define        kABErrSndPlaySync                    33
  283. #define        kABErrSndPlayAsync                    34
  284. #define        kABErrBadArgStrHandle                35
  285. #define        kABErrBadArgTextHandle                36
  286. #define        kABErrQuickTimeErrorCatch            37
  287. #define        kABErrBadArgFSSpecPtr                38
  288. #define        kABErrQuickTimeOpenMovieFile        39
  289. #define        kABErrQuickTimeNewMovieFromFile        40
  290. #define        kABErrBadArgPicHandle                41
  291. #define        kABErrPossibleMemoryLeak            42
  292. #define        kABErrBadArgTopicSlideResource        43
  293. #define        kABErrErrorOpeningSlideFile            44
  294. #define        kABErrInvalidSlideElementCount        45
  295.  
  296. //    dialog resources
  297. //
  298. //    kABmodalDialog is the resource ID# for the about box dialog
  299.  
  300. #define        kABmodalDialog                        5001
  301. #define        kABmoveableModalDialog                5002
  302. #define        kABmodelessDialog                    5003
  303.  
  304. //    kABerror is the resource ID# for the about box alert
  305. //    (error) dialog, used primarily by the ABoxError() function
  306. //    for reporting runtime errors or possible memory leaks
  307. //    to the user/programmer.
  308. #define        kABerror                            5003
  309.  
  310. //    dialog items...
  311. //
  312. //    the following items are the dialog items contained
  313. //    within the kABmodalDialog dialog box.
  314. #define        kAboutBoxOK                            1
  315. #define        kAboutBoxAppAndVersion                2
  316. #define        kAboutBoxTopic                        3
  317. #define        kAboutBoxSlideField                    4
  318. #define        kAboutBoxPrevButton                    5
  319. #define        kAboutBoxNextButton                    6
  320. #define        kAboutBoxPlayButton                    7
  321. //    these next items are pseudo-items, used in mapping
  322. //    up/down arrows to DITL objects
  323. #define        kAboutBoxPreviousTopic                8
  324. #define        kAboutBoxNextTopic                    9
  325.  
  326. #define        kActivateControl            0
  327. #define        kDeactivateControl            0
  328.  
  329. //    general bad things...
  330. //
  331. //    these defines are used to provide a more readable context
  332. //    for error checking in the code. This list will constantly
  333. //    vary as modifications are made to the about box.
  334. #define        kABemptyStringLength            (0)
  335. #define        kABbadDialogItem                (0)
  336. #define        kABbadCautionAlertItem            ((short)-1)
  337.  
  338. //    general good things...
  339. //
  340. //    these defines are helpful constants used in various places of
  341. //    the about box code.
  342. #define        kABallocateDialogRecordStorage    ((Ptr)0)
  343. #define        kABdialogInFront                ((WindowPtr)-1)
  344. #define        kABfileNameLength                ((short)32)
  345. #define        kABlongNameLength                ((short)80)
  346. #define        kABstringSeparator                ("\p/")
  347. #define        kABcaseSensitive                (true)
  348. #define        kABcaseInsensitive                (false)
  349. #define        kABdiacriticalSensitive            (true)
  350. #define        kABdiacriticalInsensitive        (false)
  351.  
  352. //    file type information for PBx calls; these defines
  353. //    are usually always used in conjunction with a PBGetCatInfo()
  354. //    call or some other PBxxx file manager function call.
  355. #define        kABpbIsDirectory                0x0010
  356. #define        kABpbQuery1Item                    ((short)0)
  357. #define        kABpbQueryDirectory                ((short)-1)
  358.  
  359.  
  360. /*================ Enums =================*/
  361.  
  362. //     key equates for keyboard navigation of the about box
  363. //
  364. //    the enter, return, and escape keys function as normal in a modal dialog
  365. //    the tab key really isn't used by the about box
  366. //    the backspace really isn't used by the about box
  367. //    the delete really isn't used by the about box
  368. //    the left arrow will move to the preceeding slide
  369. //    the right arrow will move to the next slide
  370. //    the up arrow will move to the preceeding topic
  371. //    the down arrow will move to the next topic
  372. enum  {
  373.         kEnterKey = 0x03, 
  374.         kBackSpace = 0x08, 
  375.         kTabKey = 0x09, 
  376.         kReturnKey = 0x0D, 
  377.         kEscKey = 0x1B, 
  378.         kLeftArrow = 0x1C, 
  379.         kRightArrow = 0x1d, 
  380.         kUpArrow = 0x1e,
  381.         kDownArrow = 0x1f,
  382.         kSpace = 0x20,
  383.         kDeleteKey = 0x7F
  384. };
  385.  
  386.  
  387.  
  388. /*=============== Structs ================*/
  389. /*=============== Typedefs ===============*/
  390. /*========== Function Prototypes =========*/
  391.  
  392.  
  393.  
  394. #endif    // _ABoxDefs_
  395.  
  396. //    end of file
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.